FR-132 v2.8: harden the Examples picker for host-supplied corpora - #19
Merged
Conversation
User-reported regression: the docs-site embed's Examples picker showed all 163 cases "duplicated and uncategorised". Root cause: FR-132's tier/rule joins happen only inside buildExampleCorpus, which a host-supplied host.examples override bypasses — the docs site hand-maps the engine corpus (dropping rule/tier), so everything fell into one "Reference · other" optgroup, and the doc-first-sentence labels are not unique (the pinned corpus collides in three rule groups even when categorised), so distinct cases rendered identical labels. SPEC-first amendment of FR-132 (v2.8, no new IDs): - Colliding labels within a group are disambiguated with " — <case name>". - A corpus with no tier/rule membership at all renders as a flat, ungrouped list — no fabricated "other" header. - The corpus derivation is exported for embedders. Implementation: - examples.ts: split buildExampleCorpusFromDocs(docs) out of buildExampleCorpus — takes the EditorDocs shape, isomorphic to the engine get_all_docs() payload, so hosts derive instead of hand-mapping. - panels.tsx: groupExamples returns a label:null group for group-less corpora (rendered without optgroup chrome; partially categorised corpora keep "Reference · other"); disambiguatedLabels suffixes per group. - editor-react + editor-element re-export buildExampleCorpus / buildExampleCorpusFromDocs (+ EditorDocs/EditorMetadata types). Tests red-first (examples-picker.test.tsx): flat degradation, mixed-corpus "other" retention, collision suffix, per-group disambiguation scoping, from-docs parity. Traceability FR-132 row updated in the same change. Gates green (traceability, parity 23/29/34, snapshot); live-verified in the Pyodide reference host: 163 options, 22 groups, 0 duplicate values, 0 remaining within-group label collisions. Follow-up (docs-site repo): swap toExampleCases for the exported buildExampleCorpusFromDocs once a new editor tarball is released, restoring tiers/rule groups in the embedded picker. Refs: FR-132, FR-009 Slice: fix-examples-picker-host-corpus Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
WalkthroughThe change documents FR-132 in SPEC v2.8, extracts a docs-based example-corpus builder with package re-exports, and updates the Examples picker to disambiguate duplicate labels and render fully ungrouped host corpora as flat lists. ChangesFR-132 picker hardening
Estimated code review effort: 3 (Moderate) | ~20 minutes Sequence Diagram(s)sequenceDiagram
participant Host as Host
participant Builder as buildExampleCorpusFromDocs
participant Docs as EditorDocs
participant Panel as ExamplesPanel
participant Select as HTML select
Host->>Builder: provide EditorDocs
Builder->>Docs: read rules, worked_examples, and recipes
Docs-->>Builder: provide tier and rule associations
Builder-->>Panel: return ExampleCase[]
Panel->>Panel: group examples and disambiguate labels
Panel->>Select: render optgroups or flat options
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/editor-ui/test/examples-picker.test.tsx`:
- Around line 132-142: Update both tests in
packages/editor-ui/test/examples-picker.test.tsx at lines 132-142 and 165-177 to
include comments citing FR-132 (v2.8), using the requirement descriptions
provided for the partially categorised corpus and per-group scoping cases.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 5b5baae4-9849-4ee5-920d-cdb87da78cfe
📒 Files selected for processing (9)
docs/SPEC.mddocs/current-state.mddocs/traceability.mdpackages/editor-element/src/index.tspackages/editor-react/src/index.tspackages/editor-ui/src/components/panels.tsxpackages/editor-ui/src/index.tspackages/editor-ui/src/session/examples.tspackages/editor-ui/test/examples-picker.test.tsx
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #19 +/- ##
==========================================
+ Coverage 78.46% 78.80% +0.33%
==========================================
Files 38 38
Lines 2907 2930 +23
Branches 464 473 +9
==========================================
+ Hits 2281 2309 +28
+ Misses 598 595 -3
+ Partials 28 26 -2 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
…yload fallbacks - Add the FR-132 (v2.8) citation comments CodeRabbit flagged on the partially-categorised-corpus and per-group-scoping tests. - Codecov patch gaps: new sparse/malformed-docs test drives the tolerant fallback branches in buildExampleCorpusFromDocs (missing curated lists, non-list rule refs, non-string param refs, absent corpus) to 100%; panels.tsx drops a dead empty-corpus branch (the panel returns null before groupExamples runs) and an unreachable `?? 0` on a map key populated one loop earlier. Refs: FR-132 Slice: fix-examples-picker-host-corpus Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
packages/editor-ui/test/examples-picker.test.tsx (2)
185-186: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winCite FR-132 on this test directly.
The enclosing
describeincludes FR-132, but this individual test does not cite the requirement in its name or comment. Add an inline// FR-132citation or include it in the test name.As per coding guidelines: “every implemented requirement must have a test that cites its requirement ID in the test name or a comment.” As per path instructions: “Tests must cite the requirement ID they cover.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/editor-ui/test/examples-picker.test.tsx` around lines 185 - 186, Add a direct FR-132 citation to the individual test named “derives the same tier/rule joins as buildExampleCorpus from a bare docs payload,” either in its test name or as an inline comment, while preserving the existing test behavior.Sources: Coding guidelines, Path instructions
187-188: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winMake the corpus assertion independent.
buildExampleCorpusdelegates directly tobuildExampleCorpusFromDocsinpackages/editor-ui/src/session/examples.ts:69-75, so this equality assertion compares the helper with itself through a wrapper and cannot catch shared regressions. Assert the expected ordering and{ name, rule, tier }projections instead.Proposed test assertion
- expect(corpus).toEqual(buildExampleCorpus(fakeMetadata)); + expect(corpus.map(({ name, rule, tier }) => ({ name, rule, tier }))).toEqual([ + { name: 'Worked1', rule: undefined, tier: 'worked-example' }, + { name: 'Recipe1', rule: undefined, tier: 'recipe' }, + { name: 'RefB', rule: 'attr', tier: undefined }, + { name: 'RefA', rule: 'map', tier: undefined }, + { name: 'RefC', rule: 'attr', tier: undefined }, + { name: 'Orphan', rule: undefined, tier: undefined }, + ]);🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/editor-ui/test/examples-picker.test.tsx` around lines 187 - 188, Make the corpus assertion in the examples picker test independent of buildExampleCorpus: after calling buildExampleCorpusFromDocs, assert the expected item ordering and each item’s { name, rule, tier } projection directly. Do not compare against buildExampleCorpus, which delegates to the same helper and cannot detect shared regressions.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@packages/editor-ui/test/examples-picker.test.tsx`:
- Around line 185-186: Add a direct FR-132 citation to the individual test named
“derives the same tier/rule joins as buildExampleCorpus from a bare docs
payload,” either in its test name or as an inline comment, while preserving the
existing test behavior.
- Around line 187-188: Make the corpus assertion in the examples picker test
independent of buildExampleCorpus: after calling buildExampleCorpusFromDocs,
assert the expected item ordering and each item’s { name, rule, tier }
projection directly. Do not compare against buildExampleCorpus, which delegates
to the same helper and cannot detect shared regressions.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 9d0341dd-5695-4d32-9899-02f3b622b1ba
📒 Files selected for processing (2)
packages/editor-ui/src/components/panels.tsxpackages/editor-ui/test/examples-picker.test.tsx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Fixes the user-reported regression "examples are duplicated and uncategorised" in the embedded Examples picker. SPEC-first amendment of FR-132 (SPEC v2.7 → v2.8, no new IDs), then the implementation:
" — <case name>". The engine guarantees unique names, not unique doc sentences: the pinned corpus already collides in three rule groups (attr,join,this) even when fully categorised.buildExampleCorpusFromDocs(docs)is split out ofbuildExampleCorpusand re-exported from@transon/editor-reactand@transon/editor-element(with theEditorDocs/EditorMetadatatypes). It takes the metadata-contract §2.7 docs shape, which is isomorphic to the engine'sget_all_docs()payload.Why
FR-132 (shipped in v0.2.0) derives
tier/ruleonly insidebuildExampleCorpus— but a host-suppliedhost.examplesoverride bypasses that derivation entirely. The docs-site embed (transon-org.github.io→EditorView.tsx→toExampleCases) hand-maps the engine corpus to{name, doc, tags, template, data, result}, dropping the join keys, so its picker rendered all 163 cases in one "Reference · other" group ("uncategorised") with colliding labels covering 13 entries ("duplicated"). The oldpanels.tsxcomment claiming host corpora "flow through the same derivation" was wrong — that comment is fixed too.Reviewer notes
examples-picker.test.tsx: flat degradation, mixed-corpus "other" retention, collision suffixing, per-group scoping of disambiguation (the same sentence under two different rules stays bare), andbuildExampleCorpusFromDocs/buildExampleCorpusparity. The pre-existing test that asserted the['Reference · other']behavior for host corpora was updated to the amended SPEC.?metadata=engine&engine=0.2.2paths): 163 options, 22 groups, 0 duplicate values, 0 remaining within-group label collisions, console clean.toExampleCaseswith the exportedbuildExampleCorpusFromDocsonce a new editor tarball is released — that's what restores the Worked examples / Recipes / per-rule groups in its embedded picker.Refs: FR-132, FR-009
🤖 Generated with Claude Code
Summary by CodeRabbit
buildExampleCorpusFromDocsfor building example corpora from documentation data.EditorDocsandEditorMetadatatypes in editor packages.